Adding Images to Blog Content
A blog post with zero images is a blog post that gets skimmed once and abandoned. Images are not decoration — they are retention engines. They break reading fatigue, create visual anchors in the F-pattern scan, and open a second traffic channel through Google Image Search that most writers completely ignore.
The goal is not to "add images." The goal is to place the right image at the exact moment the reader's brain needs a mental break.
Part 1 — What Google Actually Reads in an Image
Google cannot see your image. It reads the signals around it. Most bloggers get this wrong — they upload a beautiful photo and call it done. The SEO value lives in the metadata.
| Signal | What it is | Your Control |
|---|---|---|
| Alt text | A text description of the image | Direct — you write it |
| File name | The filename before you upload | Direct — rename before upload |
| Caption | The text immediately below the image | Direct — add one |
| Surrounding text | The paragraph above and below | Indirect — structured content |
Uploading a photo named IMG_20250115_083412.jpg. Google's crawler indexes the filename as a keyword signal. IMG_20250115_083412.jpg ranks for nothing. content-formatting-checklist-example.webp is crawlable and discoverable.
Rename every image before it leaves your desktop.
Part 2 — The Right Image for the Right Moment
Choosing where to place an image is more important than choosing which image to use. Use the "Show Don't Tell" rule: place an image at the exact moment the text introduces something easier to show than to explain.
flowchart TD
A["Writing a section"] --> B{"Can I show this\nfaster than I can tell it?"}
B -- No --> C["Use prose — no image needed"]
B -- Yes --> D{"What type of visual?"}
D --> E["Data/Stats → Screenshot or Chart"]
D --> F["Process/Steps → Annotated Screenshot"]
D --> G["Comparison → Side-by-side image"]
D --> H["Concept → Diagram or Infographic"]
The 3 High-Value Image Types for Blogs
- Annotated Screenshot
- Infographic or Diagram
- Data Chart / Graph
When to use: Tutorials, how-to posts, tool reviews.
An annotated screenshot is the highest-trust image in blog writing. It proves you actually did the thing. A stock photo proves nothing.
The pattern:
- Take a screenshot of the actual tool, dashboard, or result.
- Add a red arrow or circle annotation pointing to the key element.
- Write an alt text that describes both the UI and the action.
When to use: "How it works" posts, comparison posts, framework explanations.
An infographic is a standalone skim layer — a user who never reads a word of your prose can still get value from a good infographic. That engagement signal (time on page, scroll depth) tells Google the content is useful.
The pattern:
- Title the infographic clearly inside the image itself.
- Always repeat the key takeaway in the caption below.
- Alt text should describe the content of the infographic, not just label it.
When to use: Case studies, research posts, "X increased by Y%" claims.
A chart turns a statistic into proof. "Traffic increased 340%" is a claim. The same claim with a screenshot of the Google Analytics trend line is evidence. Evidence earns backlinks. Claims do not.
The pattern:
- Always show the date range and the metric name in the chart.
- Add a caption that states the key finding in one sentence.
- Alt text must describe the numbers, not just call it "a chart."
Part 3 — Writing Alt Text That Ranks
Alt text is a 125-character slot where you describe the image for both visually impaired readers (accessibility) and Google Image Search (SEO). Most bloggers either leave it empty or stuff it with keywords. Both are wrong.
The Formula
[Type of visual] + [Subject and what it shows] + [Natural keyword if appropriate]
- ❌ Weak Alt Text
- ✅ Strong Alt Text
Empty — zero SEO value, accessibility failure.
Keyword stuffed — triggers spam filters, penalized by Google.
Too vague — "image" is redundant (Google knows it's an image). "SEO" has no context.
Describes the type (bar chart), the comparison being made, and the specific numbers. Naturally contains the keyword phrase "FAQ" and "CTR" without stuffing.
Part 4 — Image Placement Rules
Placing images correctly increases dwell time. Placing them incorrectly breaks the reading flow and reduces time on page.
| Placement | Effect | Verdict |
|---|---|---|
| Hero image at the top (relevant) | Sets context, reduces bounce | Use it |
| Generic stock photo at the top | Increases LCP load time, adds no value | Avoid |
| Image directly after the concept it illustrates | Confirms understanding, increases scroll depth | Best practice |
| Image dropped randomly between unrelated paragraphs | Breaks cognitive flow | Never do this |
| Three images back-to-back | Causes image fatigue, user starts skipping | Spread them out |
Place at least one visual element (image, diagram, callout, or table) for every 300–400 words of body text. This matches the average smartphone scroll depth — the user should never see an unbroken wall of text that fills more than one full mobile screen.
Part 5 — MDX Implementation Reference
These are the three syntax patterns you will use in Docusaurus MDX blog posts:
Standard image (responsive markdown):
Image with controlled width (JSX):
<img
src="/img/your-filename.webp"
alt="Your descriptive alt text here"
style={{ width: '100%', maxWidth: '720px', display: 'block', margin: '0 auto' }}
/>
External image:
maxWidth, not a fixed widthA fixed pixel width like width="500px" breaks on mobile. maxWidth: '720px' scales the image down for smaller screens while capping it on desktop. Always use maxWidth.
Part 6 — Output Checklist
Before publishing, verify every image in the post:
- File name is descriptive and lowercase-with-hyphens (not
IMG_0045.jpg). - Alt text follows the formula: type + subject + natural keyword.
- Format is WebP whenever possible (smallest file, best quality-to-size ratio).
- File size is under 150KB (compress at Squoosh.app if needed).
- Placement is at the exact point where the image explains or confirms the adjacent text.
- No image is purely decorative — every image must add informational value.